Kanzi Studio plugins extend the functionality of Kanzi Studio and run in Kanzi Studio. Use a Kanzi Studio plugin to:
Kanzi Studio plugin interface is provided as .NET framework assembly. You can find it in <KanziInstallation>/Studio/Bin/PluginInterface.dll. The plugin interface provides access to data and commands in Kanzi Studio. To develop a Kanzi Studio plugin:
Kanzi Studio command plugins are plugins that you execute as a single command and do not have a user interface. For example, use the command plugins to execute a command on the entire or the selected part of the scene graph in your project.
Here you create the base for a Kanzi Studio command plugin where you then add functionality that extends the functionality of Kanzi Studio.
To create a Kanzi Studio command plugin:
System.ComponentModel.Composition
.Class1.cs
file and add the using directive for the System.ComponentModel.Composition
and the Kanzi Studio plugin interface:using System.ComponentModel.Composition; using Rightware.Kanzi.Studio.PluginInterface;
PluginCommand
interface, use the export attribute to tell Kanzi Studio that the .dll is a plugin. In this example, you implement the plugin in the Class1
class.[Export(typeof(PluginContent))]
Class1
class to implement the PluginCommand
interface, which you implement in the Class1
class. Kanzi uses this class to create the plugin.public class Class1
public class Class1 : PluginCommand
PluginCommand
and select Implement Interface.throw new NotImplementedException();
Make sure that your plugin handles all its internal exceptions and does not let them reach the Kanzi Studio interface.
For example, set the functions in theClass1
class to:CanExecute
function to set whether users can launch your plugin, and where they can launch your plugin:
false
, Kanzi Studio shows the plugin in the main menu and the context menu, but users cannot launch the plugin.true
, users can launch the plugin.For example, use this to enable the command only when a Kanzi Studio project is open
return this.studio != null && this.studio.Project != null;
CommandPlacement
function to set the menu name of the plugin, and where you want to show the command to launch the plugin:
ContextMenuPlacement.NONE
.ContextMenuPlacement.PROJECT_ITEM
.get { return new CommandPlacement("myPluginMenu", ContextMenuPlacement.NONE, false, null); }
Description
function to set a brief description of what your Kanzi Studio plugin does. Kanzi Studio shows this description as a tooltip when a user hovers the mouse pointer over the plugin name in the menu.get { return "A tooltip with short description of what the plugin does."; }
DisplayName
function to show the plugin name in the Kanzi Studio menu where you can launch the plugin.get { return "Plugin display name"; }
Initialize
function to place studio
to a member variable.KanziStudio
object to plugins and is the root object for data access. KanziStudio
object provides the current project, available commands, global undo and redo, events related to project opening and closing.private KanziStudio studio; public void Initialize(KanziStudio studio) { this.studio = studio; }
Name
function to set the internal name of your plugin. Kanzi uses the internal name of the plugin so that you can change the display name of your plugin without additional changes to the plugin.get { return "Internal plugin name"; }
Execute
function the code you want your plugin to run.studio.Log("Hello world!");
Here you created just the base structure for your Kanzi Studio plugin, which only prints a message to the Kanzi Studio Log window. To make your plugin do more than that, add the code that you want your plugin to run to the Execute
function. See Adding functionality to your Kanzi Studio command plugin.
To build and run a Kanzi Studio plugin:
Copy the Kanzi Studio plugin .dll to the %ProgramData%\Rightware\<KanziVersion>\plugins directory.
If the plugins directory does not exist in %ProgramData%\Rightware\<KanziVersion>, create it.
To debug a Kanzi Studio plugin:
Here you can find an example of a Kanzi Studio plugin. This plugin deletes all Empty Node nodes that do not have child nodes.
To delete Empty Node nodes without child nodes using a Kanzi Studio plugin:
PluginCommand
interface.Execute
function write the code that your plugin executes when you invoke the plugin command.Execute
function:// Plugin executes the content of this function. Place your plugin code here. public void Execute(PluginCommandParameter parameter) { var items = parameter.Items; // Print to the Kanzi Studio Log window. studio.Log("Deleting all Empty Node nodes without child nodes"); // When executing from the main menu, items passes empty value as a parameter. // When executing from the context menu, items passes the selected items as a parameter // (even when multiple items are selected). if (items != null && items.Any()) { // If executed from the context menu, start the function that traverses // the scene graph from the node where it is executed. TraverseTree(items); } else { // Check that a project is opened. if (studio != null && studio.Project != null && studio.Project.Screen != null) { // If executed from the main menu, starts the function that traverses // the scene graph from the first child of the Screen node. TraverseTree(studio.Project.Screen.Children); } } } // TraverseTree function traverses the scene graph from the node where you launch the plugin. private void TraverseTree(IEnumerable<ProjectItem> items) { foreach (var item in items.ToArray()) { // If the node is an Empty Node 2D or Empty Node 3D and does not have // any child nodes, delete it. if ((item is EmptyLayer || item is EmptyNode) && !item.Children.Any()) { // Delete the project item using a command. This enables you // to undo the action performed by the plugin. studio.Commands.DeleteProjectItem(new ProjectItem[] { item }); } // Traverse the children of the current node. else if (item.Children.Any()) { TraverseTree(item.Children); } } }
CanExecute
function set where and how you can launch the plugin in Kanzi Studio.public bool CanExecute(PluginCommandParameter parameter)
{
// Allow launching of the plugin only when a single node in the scene graph is selected.
// Zero items are called when executing the plugin from the main menu, which sets the
// plugin to start traversing the scene graph from the first child node of the Screen node.
var items = parameter.Items;
return items != null && items.Count() <= 1;
}